# 网络与通信库

```{admonition} 本文引用的文件
:class: note

- `firmware/port/modules/urequests.py`
- [docs/docs/zh_CN/library/mPython/urequests.rst](../../../../products/mpython/library/mPython/urequests.rst)
- `firmware/port/modules/umqtt/simple.py`
- `firmware/port/modules/umqtt/robust.py`
- [docs/docs/zh_CN/library/mPython/umqtt.simple.rst](../../../../products/mpython/library/mPython/umqtt.simple.rst)
- `esp32s3/firmware/modules/radio.py`
- [docs/docs/zh_CN/library/mPython/radio.rst](../../../../products/mpython/library/mPython/radio.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)
```

## 产品概述
本章节面向 mPython/ESP32-S3 平台的网络与通信能力，聚焦四类常用接口：HTTP 客户端（urequests）、MQTT 客户端（umqtt.simple）、无线广播（radio，基于 ESP-NOW）以及低功耗蓝牙（bluetooth）。它们分别覆盖“请求-响应”的 HTTP 访问、轻量级发布/订阅消息、短距无连接组网与 BLE 设备互联等典型物联网场景，适合传感器数据上报、远程控制、设备间近场通信与云端交互。

## 核心业务流程
- HTTP 客户端流程
  - 解析 URL、选择端口与协议（http/https）
  - 建立 socket 连接（可选 SSL）
  - 组装请求头与正文（表单/JSON/文件上传）
  - 发送请求并读取响应状态码与头部
  - 封装 Response 对象，提供 content/text/json 便捷访问
- MQTT 客户端流程
  - 创建 MQTTClient，配置服务器、认证、保活、遗嘱
  - 建立 TCP/SSL 连接并完成握手
  - 发布/订阅主题，设置回调处理入站消息
  - 通过 wait_msg/check_msg 在主循环中驱动消息收发
  - robust 版本在异常时自动重连
- 无线广播（ESP-NOW）流程
  - 初始化 Wi-Fi STA/AP 与 ESP-NOW 栈
  - 添加对端 MAC（支持加密/PMK）
  - 发送单播/广播消息，接收回调或轮询
  - 查询对端列表、MAC、RSSI 等信息
- BLE 流程
  - 启用 BLE，配置地址模式、MTU、配对参数等
  - 作为广播者/观察者/中央/外围角色运行
  - 注册 GATT 服务/特征，读写/通知/指示
  - 发现远程服务/特征/描述符，执行读/写/交换 MTU
  - 使用 L2CAP 通道进行面向连接的数据传输

```text
graph TB
A["应用代码"] --> B["HTTP 客户端<br/>urequests"]
A --> C["MQTT 客户端<br/>umqtt.simple / robust"]
A --> D["无线广播<br/>radio (ESP-NOW)"]
A --> E["BLE 模块<br/>bluetooth"]
B --> F["TCP/SSL 套接字"]
C --> G["TCP/SSL 套接字"]
D --> H["ESP-NOW 栈"]
E --> I["BLE 控制器/GAP/GATT/L2CAP"]
```

**图表来源**
- `firmware/port/modules/urequests.py:41-165`
- `firmware/port/modules/umqtt/simple.py:8-103`
- `esp32s3/firmware/modules/radio.py:19-45`
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:23-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

**章节来源**
- `firmware/port/modules/urequests.py:41-165`
- `firmware/port/modules/umqtt/simple.py:8-103`
- `esp32s3/firmware/modules/radio.py:19-45`
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:23-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

## 功能模块清单
- urequests（HTTP 客户端）
  - 职责：提供简洁的 HTTP 请求方法（GET/POST/PUT/PATCH/DELETE/HEAD），统一封装响应体与 JSON 解析，支持表单/JSON/文件上传与 HTTPS。
  - 用户价值：快速对接 Web API、云平台与本地服务；减少底层 socket 编程复杂度。
  - 验收要点：URL 解析正确、参数编码、Content-Type 设置、HTTPS 握手、响应状态码与文本/JSON 获取、超时与错误提示。
- umqtt.simple（MQTT 客户端）
  - 职责：实现 MQTT 连接、发布、订阅、心跳与遗嘱；robust 版本提供断线重连。
  - 用户价值：稳定可靠的发布/订阅消息通道，适配弱网与延迟环境。
  - 验收要点：连接/断开、QoS0/1 发布、订阅回调触发、遗嘱生效、check_msg/wait_msg 行为、异常重连。
- radio（无线广播，ESP-NOW）
  - 职责：基于 ESP-NOW 的无连接短距通信，支持多通道、对端管理、广播/单播、RSSI 与加密。
  - 用户价值：多板组网、低开销、低延迟的近场通信。
  - 验收要点：通道配置、对端添加/删除、发送成功返回、接收字符串/字节、广播与 RSSI、加密 PMK。
- bluetooth（BLE）
  - 职责：提供 GAP/GATT/L2CAP 的低功耗蓝牙能力，涵盖广播、扫描、连接、服务发现、读写通知、配对绑定。
  - 用户价值：构建 BLE 外设/中心设备，实现手机/网关/传感器互联。
  - 验收要点：active/config/irq 事件、gap_advertise/gap_scan/gap_connect、gatts/gattc 操作、L2CAP 收发、MTU 交换、配对与密钥存储。

**章节来源**
- [docs/docs/zh_CN/library/mPython/urequests.rst:14-101](../../../../products/mpython/library/mPython/urequests.rst)
- [docs/docs/zh_CN/library/mPython/umqtt.simple.rst:17-86](../../../../products/mpython/library/mPython/umqtt.simple.rst)
- [docs/docs/zh_CN/library/mPython/radio.rst:9-48](../../../../products/mpython/library/mPython/radio.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:17-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

## 数据与状态
- HTTP 响应模型
  - Response 对象缓存 body，提供 content（bytes）、text（str）、json（dict）与 recv。
  - 内部维护 raw socket 引用，close 释放资源。
- MQTT 会话与消息
  - MQTTClient 维护 client_id、server/port、ssl、keepalive、遗嘱、PID 与回调。
  - publish 支持 QoS0/1；wait_msg/check_msg 驱动消息分发。
  - robust.MQTTClient 在 OSError 时指数退避重连。
- ESP-NOW 对端与队列
  - MPythonESPNow 维护 peer_list、broadcast 标志、Wi-Fi 通道与加密 PMK。
  - 支持 send_data/send_msg/broadcast_data，recv/recv_msg 返回源地址与数据，含 RSSI（平台相关）。
- BLE 角色与句柄
  - BLE 对象管理活动状态、配置项（mac/addr_mode/gap_name/mtu/bond/mitm/io/le_secure）。
  - GAP：广播 interval_us、扫描 duration_ms/interval/window、连接参数。
  - GATT：服务/特征/描述符句柄，读写/通知/指示、缓冲大小。
  - L2CAP：PSM/CID/MTU 与信用流控。

```text
classDiagram
class Response {
+raw
+encoding
-_cached
+close()
+content
+text
+json()
+recv(dataLen)
}
class MQTTClient {
+client_id
+server
+port
+ssl
+keepalive
+lw_topic
+lw_msg
+cb
+connect(clean_session)
+disconnect()
+ping()
+publish(topic, msg, retain, qos)
+subscribe(topic, qos)
+wait_msg()
+check_msg()
}
class MPythonESPNow {
+wifi_sta
+wifi_ap
+wifi_channel
+peer_list
+broadcast
+set_add_peer(peer_mac)
+send_data(peer_id, msg)
+send_msg(peer_mac, msg)
+broadcast_data(msg)
+recv(timeout_ms)
+get_peer_list(encrypt)
+get_mac(mode)
+deinit()
}
class BLE {
+active([active])
+config(param=value...)
+irq(handler)
+gap_advertise(interval_us, adv_data, resp_data, connectable)
+gap_scan(duration_ms, interval_us, window_us, active)
+gap_connect(addr_type, addr, scan_duration_ms, min_conn_interval_us, max_conn_interval_us)
+gatts_register_services(services_definition)
+gattc_discover_services(conn_handle, uuid)
+l2cap_listen(psm, mtu)
+l2cap_connect(conn_handle, psm, mtu)
}
Response --> "uses" usocket
MQTTClient --> "uses" socket
MPythonESPNow --> "uses" network.WLAN
BLE --> "uses" bluetooth 控制器
```

**图表来源**
- `firmware/port/modules/urequests.py:7-38`
- `firmware/port/modules/umqtt/simple.py:8-103`
- `esp32s3/firmware/modules/radio.py:13-160`
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:23-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

**章节来源**
- `firmware/port/modules/urequests.py:7-38`
- `firmware/port/modules/umqtt/simple.py:8-103`
- `esp32s3/firmware/modules/radio.py:13-160`
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:23-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

## 关键约束与边界
- 协议与依赖
  - urequests 依赖 usocket/ussl/urllib.parse/ujson；仅支持 HTTP/1.0 请求格式，不支持分块传输与重定向。
  - umqtt.simple 仅实现 QoS0/1；QoS2 未实现以控制固件体积；所有主题与消息为字节。
  - radio 基于 ESP-NOW，需在同一频道内通信，最大包长受协议限制（文档示例为 250 字节级别）。
  - bluetooth 为底层 BLE 抽象，部分特性（如 L2CAP）在不同堆栈/平台上可用性不同。
- 性能与资源
  - HTTP 请求默认超时（例如 30 秒），注意内存占用与网络抖动。
  - MQTT 主循环需定期调用 wait_msg/check_msg 以处理消息；robust 版本有重连延时。
  - ESP-NOW 适合短距、低开销、多节点组网；加密会引入额外开销。
  - BLE 广播间隔与扫描窗口影响功耗与发现速度；MTU 协商影响吞吐。
- 安全与配置
  - HTTPS 需要证书校验策略由底层实现决定；MQTT 可配置用户名/密码与遗嘱。
  - ESP-NOW 支持 PMK 加密与 LMN；BLE 支持配对/绑定与 MITM 选项。
- 兼容性
  - 不同板型/固件可能包含/排除某些模块（如 radio 在 ESP32 与 ESP32-S3 的实现差异）。
  - BLE 常量与事件需在应用中自行定义（节省空间）。

**章节来源**
- `firmware/port/modules/urequests.py:41-165`
- [docs/docs/zh_CN/library/mPython/umqtt.simple.rst:81-86](../../../../products/mpython/library/mPython/umqtt.simple.rst)
- [docs/docs/zh_CN/library/mPython/radio.rst:9-48](../../../../products/mpython/library/mPython/radio.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:210-258](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

## 详细 API 参考

### urequests（HTTP 客户端）
- 类与方法
  - Response
    - close()：关闭底层 socket 并清理缓存
    - content：返回响应体字节（带缓存）
    - text：按 encoding 解码为字符串
    - json()：将响应体解析为 dict
    - recv(dataLen)：从原始流读取指定长度
  - request(method, url, data=None, json=None, headers={}, params=None, files=None)
    - 支持 GET/POST/PUT/PATCH/DELETE/HEAD 快捷函数
    - 自动处理 URL 参数编码、表单/JSON 序列化、文件上传 multipart/form-data
    - 支持 https（ussl）与 http（明文）
- 典型用法
  - 获取 JSON 数据：get(url).json()
  - 提交表单：post(url, data={...})
  - 上传文件：post(url, files={'name': ('path', 'type')})

```text
sequenceDiagram
participant App as "应用"
participant UR as "urequests.request"
participant Sock as "socket/ssl"
App->>UR : get/post/put/...
UR->>UR : 解析URL/参数/编码
UR->>Sock : 建立连接(可选SSL)
UR->>Sock : 发送请求头与正文
Sock-->>UR : 状态行与头部
UR-->>App : Response(content/text/json)
```

**图表来源**
- `firmware/port/modules/urequests.py:41-165`

**章节来源**
- [docs/docs/zh_CN/library/mPython/urequests.rst:14-101](../../../../products/mpython/library/mPython/urequests.rst)
- `firmware/port/modules/urequests.py:41-165`

### umqtt.simple（MQTT 客户端）
- 类与方法
  - MQTTClient(client_id, server, port=0, user=None, password=None, keepalive=0, ssl=False, ssl_params={})
  - set_callback(f)：设置订阅消息回调 f(topic, msg)
  - set_last_will(topic, msg, retain=False, qos=0)：设置遗嘱
  - connect(clean_session=True)：建立连接
  - disconnect()：断开连接
  - ping()：心跳
  - publish(topic, msg, retain=False, qos=0)：发布消息（QoS0/1）
  - subscribe(topic, qos=0)：订阅主题
  - wait_msg()：阻塞等待消息
  - check_msg()：非阻塞检查消息
- robust 增强
  - reconnect()：异常后自动重连
  - publish()/wait_msg()：捕获 OSError 并重连

```text
flowchart TD
Start(["启动"]) --> Init["创建MQTTClient"]
Init --> Connect{"连接成功?"}
Connect -- 否 --> Reconnect["reconnect()重试"]
Reconnect --> Connect
Connect -- 是 --> Loop{"主循环"}
Loop --> Publish["publish(topic,msg,qos)"]
Loop --> Subscribe["subscribe(topic,qos)"]
Loop --> Wait["wait_msg()/check_msg()"]
Wait --> Callback["回调f(topic,msg)"]
Callback --> Loop
Publish --> Loop
Subscribe --> Loop
```

**图表来源**
- `firmware/port/modules/umqtt/simple.py:8-103`
- `firmware/port/modules/umqtt/robust.py:20-46`

**章节来源**
- [docs/docs/zh_CN/library/mPython/umqtt.simple.rst:17-86](../../../../products/mpython/library/mPython/umqtt.simple.rst)
- `firmware/port/modules/umqtt/simple.py:8-103`
- `firmware/port/modules/umqtt/robust.py:20-46`

### radio（无线广播，ESP-NOW）
- 能力概览
  - 基于 ESP-NOW，支持多通道、对端管理、广播/单播、RSSI、加密（PMK）
  - 适用于 30 米范围内多板组网
- 主要方法
  - on()/off()：开启/关闭无线电
  - config(channel)：配置通道（1~13）
  - receive()/receive_bytes()：接收消息（字符串/字节），可返回 (msg, mac)
  - send()/send_bytes()：发送消息（字符串/字节），返回成功与否
  - 高级封装（ESP32-S3 示例）：MPythonESPNow 提供 add_peer、send_data、broadcast_data、recv、get_peer_list、get_mac、set_pmk_encrypt 等

```text
sequenceDiagram
participant A as "设备A"
participant RadioA as "radio(MPYthonESPNow)"
participant RadioB as "radio(MPYthonESPNow)"
A->>RadioA : set_add_peer(B_MAC)
A->>RadioA : send_msg(B_MAC, msg)
RadioA->>RadioB : ESP-NOW 单播
RadioB-->>RadioB : recv()/recv_msg()
Note over RadioB : 可获取MAC/RSSI(平台相关)
```

**图表来源**
- `esp32s3/firmware/modules/radio.py:46-132`

**章节来源**
- [docs/docs/zh_CN/library/mPython/radio.rst:9-48](../../../../products/mpython/library/mPython/radio.rst)
- `esp32s3/firmware/modules/radio.py:19-160`

### bluetooth（BLE）
- 角色与生命周期
  - 激活与配置：active([active])、config(...)（mac/addr_mode/gap_name/mtu/bond/mitm/io/le_secure）
  - 事件：irq(handler) 统一处理 GAP/GATT/L2CAP 事件
- GAP
  - 广播：gap_advertise(interval_us, adv_data, resp_data, connectable)
  - 扫描：gap_scan(duration_ms, interval_us, window_us, active)
  - 连接：gap_connect(addr_type, addr, scan_duration_ms, min_conn_interval_us, max_conn_interval_us)
  - 断开：gap_disconnect(conn_handle)
- GATT 服务器
  - gatts_register_services(services_definition)：注册服务/特征/描述符
  - gatts_read/write/notify/indicate：读写与推送
  - gatts_set_buffer：设置值缓冲大小
- GATT 客户端
  - gattc_discover_services/characteristics/descriptors：发现
  - gattc_read/write：读取/写入
  - gattc_exchange_mtu：交换 MTU
- L2CAP
  - l2cap_listen/connect/disconnect/send/recvinto：面向连接通道

```text
sequenceDiagram
participant Central as "中央设备"
participant Peripheral as "外围设备"
Central->>Peripheral : gap_scan -> _IRQ_SCAN_RESULT
Central->>Peripheral : gap_connect -> _IRQ_PERIPHERAL_CONNECT
Peripheral->>Central : gatts_notify/indicate
Central->>Peripheral : gattc_read/write
Central->>Peripheral : gattc_exchange_mtu -> _IRQ_MTU_EXCHANGED
Central->>Peripheral : l2cap_connect -> _IRQ_L2CAP_CONNECT
```

**图表来源**
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:261-333](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:336-466](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:469-507](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

**章节来源**
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:17-79](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)
- [esp32s3/docs/5_api/library/micropython/bluetooth.rst:261-507](../../../../products/mpython-s3/5_api/library/micropython/bluetooth.rst)

## 故障排查与最佳实践
- HTTP
  - 若出现“Unsupported protocol”或“Invalid URL”，检查 URL 格式与协议前缀
  - 大文件或慢网络建议合理设置超时与重试
  - 文件上传需确保 Content-Type 与 boundary 正确
- MQTT
  - 未设置回调即订阅会报错；确保先 set_callback
  - 主循环必须调用 wait_msg()/check_msg() 以处理消息
  - 网络不稳定时使用 robust 版本，避免频繁手动重连
- ESP-NOW
  - 对端未添加或信道不一致会导致发送失败；确认 channel 与 MAC
  - 加密需双方设置相同 PMK；否则无法解密
  - 接收侧需及时消费缓冲区，避免丢包
- BLE
  - 广播/扫描参数影响功耗与发现成功率；按需调整 interval/window
  - MTU 协商前后可测量实际吞吐；过大可能导致丢包
  - 配对/绑定需实现 _IRQ_GET_SECRET/_IRQ_SET_SECRET 以持久化密钥

[本节为通用指导，不直接分析具体文件]

## 结论
urequests、umqtt.simple、radio 与 bluetooth 共同构成了 mPython/ESP32-S3 平台的核心网络与通信能力。根据应用场景选择合适的协议与抽象层：HTTP 用于云端交互，MQTT 用于轻量消息总线，ESP-NOW 用于近场多节点组网，BLE 用于低功耗设备互联。结合本文档的 API 说明与流程图，可快速搭建稳定的 IoT 解决方案。

[本节为总结性内容，不直接分析具体文件]